home *** CD-ROM | disk | FTP | other *** search
/ Nebula 1 / Nebula One.iso / Mail / CryptorBundle.1.3 / doc / README < prev    next >
Text File  |  1996-04-05  |  10KB  |  306 lines
  1.  
  2. CryptorBundle-1.3
  3. -----------------
  4.  
  5. This is the bundle which reenables NeXTMail-Encryption. It uses
  6. PGP, one of the best encryption software which is available for
  7. free.
  8.  
  9. CryptorBundle-1.3 comes as a fat bundle, compiled for m68k, intel,
  10. sparc and hppa.  It works ONLY on NeXTSTEP 3.2 and 3.3, later versions may
  11. work or not. See the file 'CHANGES' about things that have changed
  12. since the former version of the bundle. 
  13.  
  14. Don't forget to read the FAQ before mailing me !!!
  15.  
  16.  
  17. *** Note:
  18.  
  19.     CryptorBundle does not contain a PGP executable. You MUST get
  20.     pgp (versions >= 2.6) from the ftp-archives and install it yourself. 
  21. ***************************************************************************
  22.     
  23.  
  24. 0. Copyright
  25. ------------
  26.  
  27. The PGP program and documentation as included in the bundle is
  28. Copyright Philip R. Zimmermann, 1990-1994. See the file 'pgpdoc2.txt'.
  29.  
  30. The bundle-software is copyrighted by Thomas Funke. You may distribute
  31. and use it under license, included in the file
  32. COPYING. You may not remove that file from the bundle and you may
  33. not remove this README file.
  34.  
  35.  
  36. 1. Support
  37. ----------
  38.  
  39. This software comes without support, and without any warranty of
  40. any kind.  If you need support, contact the author, Thomas Funke:
  41. thomas@gamelan.shnet.org.
  42.  
  43. But note: Support is available only for a small fee.
  44.     
  45. Bug reports are free and welcome :-)
  46.  
  47.  
  48. 2. Why CryptorBundle-1.3 ?
  49. --------------------------
  50.  
  51. NeXT has prepared Mail.app with public key encryption software
  52. since NS3.0. But because of US law, they were not allowed to export
  53. encryption software. The infamous three-letter-companies would mind ....
  54.  
  55. Thus the standard Mail.app comes without encryption SW. Now you
  56. can reenable this again, have NeXT's original GUI for public key
  57. mail encryption: Browse through your public keys, add keys to your
  58. key list just by drag and drop, send encrypted messages and decipher
  59. encrypted messages (if you have the public key, of course ... ).
  60.  
  61. All this is done inside Mail.app: No services add-on necessary,
  62. just the usual NeXT-way as NeXT has prepared it already.
  63.  
  64.  
  65. 3. How safe is it ?
  66. -------------------
  67.  
  68. Well, probably much safer than NeXT has originally planned. The
  69. algorithm used to encrypt is 'RSA', probably not hackable. 
  70. It uses the well known (free) PGP program, thus if you already 
  71. have PGP keys, you can still use them with the new bundle.
  72.  
  73. 4. How does it work ?
  74. ---------------------
  75.  
  76. Well, you should read the included PGP-docs. You should also have
  77. some idea 'what is public key encryption'. If you have a support
  78. contract with me, I might explain all this stuff to you.
  79.  
  80. So I just describe how to use it under Mail.app:
  81.  
  82.  
  83. 4.1 Key generation
  84.  
  85. As key generation with PGP is much more complicate (and safe) than
  86. what NeXT has originally planned, you still have to do this at the
  87. command line. To generate your own private (and public) key, use the
  88. command
  89.  
  90.     pgp  -kg
  91.     
  92. Be sure first that you have installed
  93. everything as described later.
  94.  
  95. When pgp asks you for the User ID, you have to enter either your
  96. mail-address (like user@foo.bar.edu) or, and this is preferred,
  97. your name and mail-address in the following format:
  98.  
  99.     Joe User <user@foo.bar.edu>
  100.  
  101. Of course you can still use any other user IDs you like, but that
  102. makes later uses quite inconvenient.
  103.  
  104. When PGP asks you for your pass phrase, enter a pass phrase you
  105. can remember but cannot be guessed easily. The pass phrase is like
  106. a password: Without it you cannot decipher encrypted mails.
  107.  
  108.  
  109. 4.2 Browsing keys
  110.  
  111. Start Mail.app, click on 'Tools -> Encryption keys' or 
  112. Info->Encryption keys in Mail-3.3. You'll see
  113. all (public) keys in your keyring. If you want to remove a key,
  114. just select it and press the 'remove'-button. The key-browser shows
  115. two (identical) text fields, which show the mail address of the
  116. corresponding key (actually the user ID). The key-ID is not shown,
  117. maybe I'll include this in a later version.
  118.  
  119.  
  120. 4.3 Adding (public) keys
  121.  
  122. Click 'Tools -> Encryption keys' in Mail.app.
  123.  
  124. If someone sends you his public key (unencrypted, of course), you
  125. just drag it from the mail into the browser key field. If the key
  126. (identified by it's key ID) is already there, nothing will happen,
  127. otherwise it'll be added to the keyring.
  128.  
  129. If you want to add a pgp key from an ascii file to your keyring,
  130. take care that the extension of the file is ".key", then just drag
  131. the file from the workspace into the key field of the key browser.
  132.  
  133.  
  134. 4.4 Sending public keys to other people.
  135.  
  136. Open a mail compose window. Select NeXTMAIL. Click 'Tools ->
  137. Encryption keys' and select the key you wish to send. Drag this
  138. key into your compose window.
  139.  
  140. Now send the mail as usual.
  141.  
  142. If you want to save a key in an ascii file, just command-drag the
  143. key into Edit.app - the ascii key will be in a Edit window which
  144. you can save under another name for example.
  145.  
  146.  
  147.  
  148. 4.5 Sending encrypted mails
  149.  
  150. Open a compose window. On the far right you'll see 2 small buttons
  151. you didn't see on your standard Mail.app before: The upper button
  152. switches mail encryption, the lower button is the 'Read receipt'
  153. button (which has become smaller now).
  154.  
  155. Switch the upper button with the lock closed.
  156.  
  157. Type your mail as usual and finally send it.
  158.  
  159. Now there are 2 possibilities: If the address is in the keyring,
  160. that key will be used. If not, a browser will open and you can
  161. select which key to use. Because the mail-address and the key ID
  162. should be corresponding (as described under 4.1), you'll usually
  163. not see the browser, but everything will work automagically.
  164.  
  165. BUG WARNING:  Reply addresses in Mail.app are always formed like 
  166. "To: Joe User <user@site.com>". Unfortunately, this would lead to 
  167. an error if you use encrytpion so you have to edit the address to 
  168. look like "user@site.com".
  169.  
  170.  
  171. 4.6 Decrypting mails
  172.  
  173. If someone sends you an encrypted mail, you'll see a small lock at
  174. the mail browser. To read the mail, NeXT asks you "Please enter
  175. your private key". Of course you'll not enter the key itself :-),
  176. but enter your PGP pass phrase which you hopefully remember (see
  177. 4.1). If everything is OK, you'll see the decrypted mail, otherwise
  178. you can try again.
  179.  
  180.  
  181. 5. Installation
  182. ---------------
  183.  
  184. *** Note Mail 3.3 ******************************************************
  185.  
  186. If you are running Mail-3.3, you don't need to perform 5.1. Just
  187. copy the bundle to  one of ~/Library/Mail, /LocalLibrary/Mail, /NextLibrary/Mail:
  188.  
  189.     cp -pr cryptor.bundle /LocalLibrary/Mail
  190.     
  191. ************************************************************************    
  192.  
  193. *** Note Mail 3.2 ******************************************************
  194.  
  195. To install CryptorBundle-1.3, you must change a few files in
  196. /NextApps/Mail.app.  Remember: It will not work on NEXTSTEP versions
  197. less than 3.2 !
  198.  
  199. 5.1 Copy the directory 'cryptor.bundle' into /NextApps/Mail.app:
  200.  
  201.     cp -pr cryptor.bundle /NextApps/Mail.app
  202.  
  203.     Be sure to have the permissions to do this :-)
  204.  
  205. ************************************************************************    
  206.  
  207. 5.3 Define the environment variable PGPPATH to be "~/.pgp". Don't forget
  208.     to include this in your .zshrc / .cshrc or whatever shell you use.
  209.     
  210.         export PGPPATH=~/.pgp   [for zsh users]
  211.     setenv PGPPATH ~/.pgp   [for tcsh or csh users]
  212.  
  213. 5.4 Create a directory  '.pgp' in your home directory. This directory will 
  214.     include all necessary PGP-Files. 
  215.     
  216.     Copy the included .pgp directory into your home dir:
  217.     
  218.         cp -pr sample.pgp ~/.pgp
  219.     
  220.     Finally copy the documentation there, too ! This is neccessary
  221.     to be able to generate keys !
  222.     
  223.         cp doc/pgpdoc*.txt ~/.pgp
  224.     
  225.     Now create a key pair for yourself. 
  226.     
  227.     Finally the pgp-directory should look like the following:
  228.     
  229.     /thomas/.pgp> ls -al
  230.     total 16
  231.     drwxr-xr-x  2 thomas      1024 Apr 19 18:17 ./
  232.     drwxr-xr-x 26 thomas      2048 Apr 18 17:59 ../
  233.     -rw-r--r--  1 thomas      3768 Feb 23 20:33 config.txt
  234.     -rw-r--r--  1 thomas      3712 Feb 17 14:41 pgp.hlp
  235.     -rw-------  1 thomas       745 Apr 19 17:09 pubring.bak
  236.     -rw-------  1 thomas       643 Apr 19 17:11 pubring.pgp
  237.     -rw-------  1 thomas        24 Apr 19 18:17 randseed.bin
  238.     -rw-------  1 thomas       692 Feb 23 22:37 secring.bak
  239.     -rw-------  1 thomas       992 Apr 19 17:09 secring.pgp
  240.  
  241.     You may edit config.txt for your needs. 
  242.     But note: Don't change the line 'verbose = 0' !!!
  243.  
  244.  
  245.  
  246. 5.8 [Optional] Install the man-page
  247. -----------------------------------
  248.  
  249. Copy the man page from doc/pgp.1 to an appropriate place.
  250. (usr/local/man/man1 for example). 
  251.  
  252.  
  253. 5.9 New dwrite
  254. --------------
  255.  
  256. Enter the following dwrite from a shell:
  257.  
  258.     dwrite Mail Encrypt NO
  259.  
  260. This will keep the padlock open, thus not encrypting
  261. mails as a default.
  262.  
  263.  
  264.  
  265. 6. Using existing pgp-keys
  266. --------------------------
  267.  
  268. If you have already pgp installed on your machine, you can use your
  269. installation as before. Just create the ~/.pgp directory as mentioned
  270. above and add symbolic links to your key-files (pubring.pgp,
  271. secring.pgp, randseed.bin).
  272.  
  273.  
  274. 7. BUGS
  275. -------
  276.  
  277. The installation is not really smooth. And if you did the installation
  278. wrong, you might experience strange effects. But generally it should
  279. not disturb your normal use of Mail.app [no warranty for this :-)]
  280.  
  281. If something goes wrong, you might consult the console-window from
  282. workspace which might have any messages .
  283.  
  284.  
  285. 8. THANKS
  286. ---------
  287.  
  288. Thanks to Next Inc. for the interface for mail encryption.
  289.  
  290. Thanks to Philip R. Zimmermann for developing PGP.
  291.  
  292. Thanks to Ernst Kloecker <ernst@cs.tu-berlin.de> for being the
  293. best beta-tester. 
  294.  
  295. Thanks to Rene' Kulschewski <rene@prz.tu-berlin.de> for the 4-fat-compiles.
  296.  
  297.     
  298. 9. FTP-sites in the US
  299. ----------------------
  300.  
  301. Because CryptorBundle no longer contains PGP, it is *NOT* illegal 
  302. to put the bundle on a ftp-server.
  303.  
  304.  
  305.  
  306.